.\" $Id: PAPI_perror.3,v 1.9 2004/10/01 15:50:30 you Exp $
.TH PAPI_perror 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
.nf
PAPI_perror   \- convert PAPI error codes to strings, and print error message to stderr.
PAPI_strerror \- convert PAPI error codes to strings, and return the error string to user.
.fi

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_perror(int " code ", char *" destination ", int " length ");"
.BI "char *PAPI_strerror(int " code ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_perror(C_INT\  code,\  C_STRING\  destination,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_perror()
fills the string 
.I destination 
with the error message corresponding to the error code
.IR code .
The function copies 
.I length 
worth of the error description string
corresponding to 
.I code 
into destination. The resulting string is always
null terminated. If length is 0, then the string is printed on stderr.

.B PAPI_strerror()
returns a pointer to the error message corresponding to the error code
.IR code .
If the call fails the function returns the NULL pointer. This function is
not implemented in Fortran.

.SH ARGUMENTS
.I code 
-- the error code to interpret
.LP
.I *destination 
-- "the error message in quotes"
.LP
.I length 
-- either 0 or strlen(destination)

.SH RETURN VALUES
On success 
.B PAPI_perror()
returns
.B "PAPI_OK."
and 
.B PAPI_strerror()
returns a non-NULL pointer.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments to 
.B PAPI_perror() 
is invalid.
.TP
.B "NULL"
The input error code to
.B PAPI_strerror()
is invalid.

.SH EXAMPLE
.nf
.if t .ft CW
int EventSet = PAPI_NULL;
int native = 0x0;
char error_str[PAPI_MAX_STR_LEN];
	
if ((retval = PAPI_create_eventset(&EventSet)) != PAPI_OK)
  {
     fprintf(stderr, "PAPI error %d: %s\\n",retval,PAPI_strerror(retval));
     exit(1);
  }	

/* Add Total Instructions Executed to our EventSet */

if ((retval = PAPI_add_event(EventSet, PAPI_TOT_INS)) != PAPI_OK)
  {
     PAPI_perror(retval,error_str,PAPI_MAX_STR_LEN);
     fprintf(stderr,"PAPI_error %d: %s\\n",retval,error_str);
     exit(1);
  }


/* Start counting */

if ((retval = PAPI_start(EventSet)) != PAPI_OK)
  handle_error(retval);
.if t .ft P
.fi

.SH BUGS
These functions have no known bugs.

.SH SEE ALSO
.BR PAPI_set_debug "(3), "
.BR PAPI_set_opt "(3), " PAPI_get_opt "(3), " PAPI_shutdown "(3), " 
